PC Media 23

home *** CD-ROM | disk | FTP | other *** search

/ PC Media 23 / PC MEDIA CD23.iso / share / prog / gapcdr1 / gapcdr.txt < prev next >

Wrap

Text File | 1995-01-03 | 162.6 KB | 6,618 lines

GAP Communications Online Software GAPCDR Door Interface Library Copyright (C) 1987-1994 by GAP Development Company. ALL RIGHTS RESERVED. No part of this manual shall be reproduced, stored in a retrieval system, or transmitted by any means, electronic, mechanical, photocopying, recording, or otherwise, without written permission from GAP Development Company. While every precaution has been taken in the preparation of this manual, GAP Development Company assumes no responsibility for errors or omissions. Neither is any liability assumed for damages resulting from the use of the information contained herein. GAPCDR is the sole and exclusive property of GAP Development Company. It is licensed and not sold to the end user with restrictions placed upon its use. GAPCDR is copyrighted by GAP Development Company. DESQview is a trademark of Quarterdeck. PCBoard is a trademark of Clark Development Corporation. WildCat! is copyrighted by Mustang Software. DigiBoard is a trademark of DigiBoard Incorporated. Contents Description 5 Major Features 5 Getting Started 7 Supported Compilers 8 Using GAPCDR 8 Points To Remember 11 Compiling And Linking 12 Using A Goto 13 BBS System Files 14 Sysop Setup And Functions 14 Configuration 15 Sysop Functions 17 Advanced Applications 18 Communications 18 DOS Window 20 Variables 22 Defines 22 Ansi Variables 22 DOOR.SYS Variables 23 Global Variables 25 Functions - Quick Reference 27 Functions - Detailed Reference 28 Index 104 Page 3 Page 4 GAP Communications GAPCDR Description GAPCDR is a professional development kit for Bulletin Board Door programmers. Written in Microsoft C version 7 and MASM version 6, it is fast, reliable, easy to use, and easy to incorporate into the serious programmer's source code. It consists of a set of C and assembler library routines to allow for easy door programming and interfacing. Borland C compatability is included. Major Features Interfaces with GAP Communications, PCBoard, WildCat, and other fine BBS programs that are capable of writing a DOOR.SYS file. Full communications support including the DigiBoard COM/Xi series of Intelligent Multi-Port boards as well as Fossil Drivers. Supports the FIFO buffers of the 16550 UART chip. Speeds up to 115,200 baud. Communications ports other than Com 1 and Com 2 possible. Supports CTS/RTS, automatically. Does not require watchdog or CTTY. Fully self contained, built in ANSI driver. Sysop sees what the caller sees. High speed text file display. Supports ANSI color and ASCII text files with no programming effort other than to make a single function call. Easy to use Random Number Generator. Informative Status Line display. Monitors keyboard activity and caller time remaining. Page 5 GAP Communications GAPCDR Easy interface to BBS system. Sysop chat with full word wrapping. Allows the sysop to shell to DOS. "Remembers" the default drive and directory which prevents file access errors. Credits caller with time spent chatting or while sysop is in a DOS shell. Sysop can twit caller without caller ever knowing the sysop is watching. Caller time can be increased or decreased. Full programmer control of whether or not to update the BBS system files. Time calculations are not dependent on the "seconds since midnight" and are thus unsusceptible to the midnight roll over. Timer routines are hardware independent. Automatic detection of multi-user system. Input routines are consistent throughout the program. Uses the latest in Microsoft C and MASM features. Extremely easy interfacing to door programs. Fully DESQView aware video routines as well as keyboard and COM input routines, and COM output routines. GAPCDR includes robust Communications routines which are fully interrupt driven. Written in highly optimized assembler, they are capable of operating at any speed which the UART on an IBM type of computer is capable of producing. The FIFO buffers in the 16550 UART are fully supported. CTS/RTS checking is automatic, and carrier detect is an integral part of each of the communications input and output routines. When there is a loss of carrier, a function in the main GAPCDR code will be called. This Page 6 GAP Communications GAPCDR function defaults to shutting down the door and returning to the BBS, however you may modify it to do whatever you wish. The built in ANSI driver makes GAPCDR a self contained unit. The driver is smart enough to know when a caller does not want ANSI sequences sent to his computer and it will filter out any such codes that pass through it. This allows you to create prompts with embedded ANSI sequences and display them without regard as to whether or not the caller has color "turned on". This also means you do not have to keep two sets of prompts (one with color attributes and one without). This is a great savings to you in precious DATA space. You may also use the ANSI driver to send color strings to the local monitor. Even if the caller is in mono mode, you may still send color strings and prompts to the ANSI driver and have them displayed in color on the local monitor. GAPCDR supports only the DOOR.SYS format for passing caller information to a door. We choose this format because of its universal acceptance and its inherent ability to remain stable. BBS programs frequently change and with those changes usually come modifications to the system files they create to interact with door programs. DOOR.SYS on the other hand was designed to include as much information about a caller as was thought necessary. Should new fields be needed to take care of new BBS features, it is a simple matter to add these new fields to the end of the file, thereby making the new version compatible with all prior versions. Most major BBS programs support DOOR.SYS. Getting Started GAPCDR is distributed in archived format. The contents of the archive should be as follows: GAPCDR.TXT - Disk based documentation. GAPCDRS.LIB - Small model Library routines. GAPCDRL.LIB - Large model Library routines. GAPCDBS.LIB - Small model Library routines for BC. GAPCDBL.LIB - Large model Library routines for BC. GAPCDR.H - Door Interface include file. GAPSTRUC.H - Door Interface include file. CDOOR.ZIP - Sample program illustrating many of the features of GAPCDR. READ.ME - Any pertinent information which you should read. Page 7 GAP Communications GAPCDR If you licensed the source code to GAPCDR you will receive most of the ASM, C, INC, H, BAT, and OBJ files that make up the GAPCDR library. We include both Microsoft and Borland batch files to compile the source modules. Supported Compilers We used the Microsoft C compiler version 8.x, the Borland C++ Compiler version 4.x, and MASM version 6. The linker and librarian were from their respective compilers. Since GAPCDR uses no floating point math, the C modules were compiled with the /FPa switch for Microsoft. This is the default for Borland, so no switches are necessary. For Microsoft C, in order to use the /FPa switch, you must tell the SETUP program that you want to create the Alternate Floating Point library. It will then create a set of libraries that make calls to the Alternate Math library instead of the Emulator Library. The difference in code size for a large model program that uses the Alternate library as opposed to the Emulator library is typically around 10k. Even if you do not use floating point arithmetic in your program, the Math Library will still be linked in because it contains the routines to do long arithmetic. So, the smaller the library, the smaller your programs! Place the GAPCDR files in your work directory. You may place the LIB files in the MSC\LIB or BORLAND\LIB directory. The text editor you use must allow control characters to be entered and displayed. The ANSI variables are initialized with literal characters and if your editor removes the ESC character from the strings, your ANSI displays will be quite messy. Using GAPCDR At the very beginning of your program, you must include the GAPCDR.H file. Without this file, nothing will work. It is normally included after the C header files that your program may need. To include the file, you type the following after including the regular C header files: #include "gapcdr.h" GAPCDR.H contains the declarations for the external global variables. In addition, it includes GAPSTRUC.H which contains the structure declarations and the function prototypes. Page 8 GAP Communications GAPCDR Note: Any of your source modules that include GAPCDR.H must have an include declaration for STDIO.H prior to including GAPCDR.H. It should be standard practice to include STDIO.H in your source modules anyway, so this shouldn't present any problems. The first thing that must be done prior to using any of the door functions, is to initialize GAPCDR itself. This is accomplished by making a call to read_cnf. Read_cnf opens the configuration file (the name of which you pass as a parameter on the door command line) and reads the first eight lines of the file. If the configuration file cannot be found, the program will end. The format of the configuration file is as follows: c:\gap The Crow's Nest 0 0 STANDARD D000 320 4 The first line of the file is the path to the BBS default directory. The second line is the name of the BBS. The third line is the Port IRQ and the 4th line is the Port Base Address. If the sysop running your program has his BBS configured to use Com Ports other than 1 or 2, he would then enter the IRQ and Base address for his Com Port on lines 3 and 4. GAPCDR derives the Port Number from the DOOR.SYS file. Lines five through eight are for the Intelligent DigiBoard multi- port Communications Card. The DigiBoard routines specifically support the COM/Xi series. All four of these lines are required even if your end users are using the Standard Interface. Line five is the Communications Port Interface. It must be one of the following: STANDARD DIGIBOARD INT14/EBIOS FOSSIL The Standard interface is the one that will normally be used. If an end user is using a DigiBoard then either the DigiBoard or Int14/EBIOS interface may be selected. Most sysops will use the Int14/EBIOS interface. All input/output to the DigiBoard is performed via Interrupt 14 calls and a Device Driver (available Page 9 GAP Communications GAPCDR from DigiBoard) handles the interface between the program and the board. The DigiBoard interface uses Direct Programming. GAPCDR talks to the board directly without the need for a Device Driver. In order to use this interface, a program called RESETDIG.EXE must be used in the AUTOEXEC.BAT file to reset the DigiBoard once when the computer is first booted. If the end user does not have this program (it is a part of the GAP Communications BBS package) then the Int14/EBIOS interface must be used. The Fossil interface is specified when a user is using a Fossil Device Driver (either BNU or X00). The Fossil interface also uses Interrupt 14 calls that are specific to Fossil drivers. If the Interface is set to STANDARD or FOSSIL, then lines 6 through 8 will be ignored. If the Interface is INT14/EBIOS, then lines 6 and 7 will be ignored. Line 6 is the DigiBoard Memory Window, or the address the board uses as a communications area between itself and the Host Computer. This line is used only if the Interface is set to DIGIBOARD. It can be set to 0 if the Interface is STANDARD, INT14/EBIOS, or FOSSIL. Line 7 is the DigiBoard I/O Port Address. This line is used only if the Interface is set to DIGIBOARD and can be set to 0 otherwise. Line 8 is the DigiBoard Channel Number. This line is required for the DIGIBOARD and INT14/EBIOS Interfaces. It is normally 1 - 8 for the DIGIBOARD Interface and 4 - 11 for the INT14/EBIOS Interface. The Channel Number is similar to a Port Number. It tells the program which of the DigiBoard Communications ports to use. The configuration file is usually given a name similar to the name of your door program, with a CNF extension. Read_cnf will leave this file open for your use. If you have any configuration options of your own, you may place them in this file beginning with line 9. Do not read your configuration options until after making a call to init_door (which should be the second function call in your program). Upon return from init_door, you are free to read your configuration options (if any). At this time, you should close the configuration file. Normally, your program is invoked with a command line parameter giving the name of the configuration file to use: DOOR DOOR.CNF Page 10 GAP Communications GAPCDR You would use the argv parameter to your main function to extract the configuration parameter and then pass this parameter on to read_cnf. This allows the end user to use a single program (your program) with multiple configuration files. This is especially important under multi-user systems where separate configuration files are needed. The configuration file is opened as a stream, so using fgets or any of the stream input functions would be appropriate for reading the data. Remember that the file pointer is passed back to you after the call to read_cnf. An example of the first few "door" statements that might appear in a source file would be: FILE *cnf_file; // pointer to config file cnf_file = read_cnf(argv[1]); // read the cnf file init_door(); // init the door fclose(cnf_file); // close the cnf file If there were no errors, read_cnf will return. You must now make a call to init_door. Init_door uses the information derived from line 1 of the configuration file to open and read DOOR.SYS. In addition, init_door opens the communications port (if a remote user is on), initializes some global variables, initializes the random number generator, initializes the ANSI driver, and installs a Ctrl-Break handler. If there is an error, init_door will not return. Instead it will end the program. That is basically all you have to do to initialize the GAPCDR module. When your program ends, you should clean house if necessary and call leave. Leave closes the communications port and any open files, restores the ISR routines to their original state, sends a sign off message to the caller, and then exits to DOS. It is of vital importance to exit the door by making a call to leave. Failure to do so will leave communication interrupts active and the ctrl-break intercept active. The vectors to these routines will be left in the interrupt vector table and the computer will surely lock up the first time any program is run. Points To Remember To get the ball rolling, include GAPCDR.H after the C header files. To initialize the door, call read_cnf with the name of your program's configuration file. Then call init_door. Page 11 GAP Communications GAPCDR Call leave when your program is finished. All input and output should be performed through the GAPCDR functions. The sample program gives good examples on how to accomplish this. If you use the C runtime output routines such as printf or cputs, the local screen will be a mess because the internal ANSI driver will not know where the cursor is. To determine if the BBS is a single or multi user system, check the variable called multi. If it is anything other than 0, then the BBS is multi-user and you should read/write your data files with sharing attributes. Do not use any of the BBS specific functions such as read_pcbsys or read_gapuser unless you know that your program is running with the appropriate BBS system. You may want to use a flag in your configuration file to determine which system your program is running with. These functions were provided to make your programming choores easier but using them basically restricts your door to the respective BBS system that the functions interact with. To test your program, you will need a DOOR.SYS file that was written for local exit. Of course, you can always modify any DOOR.SYS file and change the first line so that it reads COM0:. A complete set of sample files are provided for testing your program under local mode. Compiling And Linking GAPCDR has already been compiled with the necessary compile time switches for both Microsoft C and Borland C. To compile your programs, use whatever switches are required for your compiler. Microsoft C cl /c /FPa door.c link door,,NUL.MAP,+GAPCDRx Borland C bcc -c door.c tlink c0x+door,door.exe,NUL.MAP,+GAPCDRBx+Cx Page 12 GAP Communications GAPCDR Where door is the name of your program and 'x' is 'S' for the small model library or 'L' for the large model library. As was mentioned previously, GAPCDR was compiled with the /FPa option for Microsoft C. The /FPa option produces smaller executable files. If you licensed the source code to GAPCDR, there are suplementary files to aid in re-compiling and librarying the source modules. GAPCDR will only compile with Microsoft C version 7 or greater and Borland C version 4 or greater. GAPCDR uses the PASCAL function calling convention. If you are unfamiliar with this calling convention it means that the parameters to a function are pushed onto the stack from left to right instead of right to left. In addition, the function being called is responsible for removing arguments from the stack. In the C calling convention, the function making the call is responsible for restoring the stack. What this means is if you make 10 calls to show_mess, there will be 10 instances where the stack must be restored upon return from the function. In the PASCAL convention, there will be only one instance where this will occur and it will be in show_mess just prior to the actual return. The end result of using the PASCAL calling convention is smaller code size. It should be noted that the PASCAL convention cannot be used with functions that take a variable number of arguments. In addition, using the PASCAL convention absolutely requires that all functions be prototyped. Otherwise the compiler will generate redeclaration errors and the linker will generate unresolved external reference errors. Using A Goto A word about using goto. If you licensed the source code to GAPCDR, you will find that we use the goto in several places. It should be pointed out that speed and compactness, combined with readability, are our number one concerns. We performed several experiments with the goto. We took a very simple function that consisted of a while loop and a few statements embodied within the loop. We took the same function and rewrote it using a counter variable and a goto and removed the while loop. The assembler output and resultant object code was 1/2 the size as that of the function that used the while loop. Page 13 GAP Communications GAPCDR We are not proposing that anyone give up the fine structure of C and use gotos as a beginning programmer in Basic might do. In fact, if you are a beginning programmer in C, you should avoid using gotos altogether until you become more proficient. BBS System Files Since we are firm believers that the BBS system files belong to the BBS and should not be altered by any door program, updating the BBS system file is not automatic. If you wish that any decrease or increase in the user's time (kept track of in the timecredit variable), be made permanent, you may, after initializing the door, call the function that opens the system file. For PCB, this would be PCBOARD.SYS. Keep track of any time credits during the door programs operation, then call the function that updates the BBS system file. For GAP, you would need to re-write DOOR.SYS with any updated information. Sysop Setup And Functions These sysop setup and function descriptions should be placed in the documentation of your door program. You should, of course, change the setup information to fit your particular needs. Door programs written with the GAPCDR Door Interface Module will run on any BBS system that is capable of writing a DOOR.SYS file. For GAP Communications and WildCat, you need do nothing special when configuring your doors. These programs will write a DOOR.SYS file automatically. For PCBoard, you must explicitly tell the Door File editor to write a DOOR.SYS file, when setting up a GAPCDR door program. Page 14 GAP Communications GAPCDR Configuration To configure the door for a particular BBS setup, a configuration file must be used. At the very minimum, this file will contain eight lines. It may contain more than eight depending upon a particular door's configuration requirements. The name of the file is usually the same as that of the door program but with a CNF extension. The minimum requirements for the file are as follows: c:\gap The Crow's Nest BBS IRQ Port Address Interface DigiBoard Window DigiBoard I/O Address DigiBoard Channel Number The first line is the full path to your BBS default directory. For GAP, this is usually C:\GAP. For PCB, this is usually C:\PCB. The second line is the name of your BBS. The third line is the IRQ that should be used for the port, and the fourth line is the Base Port Address. If you are just using Com 1 and Com 2, you may enter a 0 on these two lines. Lines five through eight are for the Intelligent DigiBoard multi- port Communications Card. The DigiBoard routines specifically support the COM/Xi series. All four of these lines are required even if you are using the Standard Interface. Line five is the Communications Port Interface. It must be one of the following: STANDARD DIGIBOARD INT14/EBIOS FOSSIL The Standard interface is the one that will normally be used. If you are using a DigiBoard then either the DigiBoard or Int14/EBIOS interface may be selected. Most sysops will use the Int14/EBIOS interface. All input/output to the DigiBoard is performed via Interrupt 14 calls and a Device Driver (available from DigiBoard) handles the interface between the program and the board. The DigiBoard interface uses Direct Programming. GAPCDR talks to the board directly without the need for a Device Driver. In order to use this interface, a program called RESETDIG.EXE must be used in the AUTOEXEC.BAT file to reset the DigiBoard once when the computer is first booted. If you do not have this program (it is a part of the GAP Communications BBS package) then the Int14/EBIOS interface must be used. Page 15 GAP Communications GAPCDR The Fossil interface is specified when a user is using a Fossil Device Driver (either BNU or X00). The Fossil interface also uses Interrupt 14 calls that are specific to Fossil drivers. If the Interface is set to STANDARD or FOSSIL, then lines 6 through 8 will be ignored. If the Interface is INT14/EBIOS, then lines 6 and 7 will be ignored. Line 6 is the DigiBoard Memory Window, or the address the board uses as a communications area between itself and the Host Computer. This line is used only if the Interface is set to DIGIBOARD. It can be set to 0 if the Interface is STANDARD or INT14/EBIOS. Line 7 is the DigiBoard I/O Port Address. This line is used only if the Interface is set to DIGIBOARD and can be set to 0 otherwise. Line 8 is the DigiBoard Channel Number. This line is required for the DIGIBOARD and INT14/EBIOS Interfaces. It is normally 1 - 8 for the DIGIBOARD Interface and 4 - 11 for the INT14/EBIOS Interface. The Channel Number is similar to a Port Number. It tells the program which of the DigiBoard Communications ports to use. GAPCDR will obtain the sysop's name from the DOOR.SYS file. You must now create a batch file to invoke the door. This batch file is placed in the directory where you told your BBS SetUp program to look for it. Such a batch file might look like this: @echo off cd \gap\doors\tourist tourist tourist.cnf cd \gap As you can see, the door is invoked by passing the configuration file name as the first parameter. You will also need to modify your doors menu files and the data file that tells the BBS what your doors are and the security level needed to access them. For GAP, these are respectively: DOORM DOORMG DOORS.DAT Page 16 GAP Communications GAPCDR If you are running multi-nodes, simply create a separate door configuration file for each node, and number them. For instance, for a 3 node system, you might have the following configuration files: TOURIST1.CNF TOURIST2.CNF TOURIST3.CNF The only difference between the three would be the 1st line which points to the default directory for the particular node. Multi-user operation is automatic.The DOOR.SYS file contains a field that specifies if the BBS is multi-user or not. Sysop Functions The following sysop functions are available while awaiting keyboard input : F5 - Shell to DOS. F8 - Twit user and return to BBS. F10 - Initiate chat with user. CF10 - Answer user page bell. Home - Main user stats. End - Displays sysop keys available. PgDn - Secondary user stats. Up Arrow - Increase user's time remaining. Dn Arrow - Decrease user's time remaining. One of the nicer features about using the TWIT key, is the user is not told that "the sysop wants them to return to the BBS". Instead, a very plain and simple message of "returning you to the BBS" is displayed. This way, the user is given no indication that the sysop is hovering about. When using the F5 shell to DOS key, to return to the door program, simply type EXIT at the DOS command prompt. It is not necessary to change directories back to the door directory. GAPCDR is smart enough to know which drive and directory the door program is in and will reset the defaults upon return from DOS. In addition, the status line will remain on the screen. It should be noted that when in a DOS shell, the GAPCDR status line is protected by intercepting BIOS video calls. If you use Page 17 GAP Communications GAPCDR ANSI.SYS replacements which write directly to the video, you will not have this protection and your status line will scroll off the screen The Up and Down Arrow keys increase and decrease the user's time respectively by 5 minutes for each press of the key. There is no indication of what is occurring (except by the fact the user's time remaining will change), so the sysop should try not to have a lead finger. The increase or decrease is effective only while the user is in the door. Whether or not these time credits (plus or minus) are made a permanent part of the user record so that upon return from the DOOR, the BBS program will recognize them, depends upon the door author. Advanced Applications GAPCDR includes a great many advanced functions which can be used with or without the BBS Door Interface (i.e., automatic status line, time left checking, keyboard timeout checking, etc). Communications The communications functions are an integral part of GAPCDR and are called automatically by an output routine if the variable local is set to 0. However, they may be used stand alone or called directly if necessary. These routines are fully self- contained with the exception of 3 global variables and 3 external functions. The global variables are: baud - Port speed gotdv - Flag signalling the presense of DESQview port - Communications Port Number The external functions are: no_carrier - Called if carrier is dropped timer - Time delay routine dv_pause - Called to give up time slice Page 18 GAP Communications GAPCDR Before using the communications routines as stand alone functions, you should make a call to dv_here so that it can set the gotdv flag. If you are not concerned about the presense of DESQview, you must declare this variable and initialize it to 0: short near gotdv = 0; Note that it must be declared such that it resides in the default data segment. If you declare the variable yourself, you must insure that the DESQVIEW.ASM module is not linked in to your program. You will need to create a dummy function called dv_pause that does nothing but return. This is necessary because even if you do not wish to use the dv_pause function, the linker will complain if it cannot find it: void _pascal dv_pause(void); Next, you must set the variable port to the port number you will be using. Ports start at 0, where COM 1 equals Port 0. Then set the variable baud to the bps rate you want the port opened at. Your program will need to include a function called no_carrier. It is prototyped as: void _pascal no_carrier(void); This function is called by the communications routines when they detect that there is no carrier. You may do whatever you wish inside this function but keep in mind that it will continue to be called if there is no carrier on the port. You most certainly do not want to make calls to any of the communications functions from inside this routine or a stack overflow will eventually result. If you wish to do your own carrier detecting (as you would if you were going to be using these functions to create a dial out type of program), then this function can simply contain a return. Once you have the global variables configured, the first step in initializing the serial port is to make a call to setport. Setport creates the receive buffer and then sets up the serial port. After the port is configured, you should then call init_port to set the baud, parity, and data bits. Init_port supports all the baud rates that a UART on an IBM type of computer is capable of utilizing. After this the port is fully configured and may now be utilized. Before your program ends, you must call reset_port to restore the interrupt vector back the way it was. Page 19 GAP Communications GAPCDR The main input routines are: comgetc - Get a single character from the port comgetd - Get a character with timeout The main output routines are: computc - Send a single character computs - Send a string There are routines for checking carrier, turning DTR on and off, checking if there are any characters in the receive buffer, and clearing the receive buffer. If you need to change baud rates simple set the variable baud to whatever bps rate you want to change to and then call init_port. DOS Window GAPCDR includes some very advanced functions for setting up what we call a DOS Window. This is a Window that you define on the local screen and to which all DOS output will be redirected. For instance, if you needed to shell to DOS to run PKUNZIP or DSZ, you could set up a DOS Window and all output from these two programs will be contained inside the window. The window can also be used without shelling to DOS although there is really no practical use for doing so. To set up a DOS window, the first thing you should do is make a call to get_attr so that the current screen colors can be stored away. This is necessary because you may want to use special colors in your DOS window. By storing the original screen attributes, they can be restored when you close the window, thereby keeping the user's screen colors the way the user likes them! At the beginning of your program call get_attr. Do this before you do any screen output. You will then make several calls to the various GAPCDR functions to setup your DOS window. Once it is configured, you can then shell to DOS and do whatever you like. All screen output will take place inside the window. Please note that if you use a console driver other than CON or ANSI.SYS (and this generally includes all so called video speed up programs), or run a program that writes directly to the screen, then output will not take place inside of the window. This is because video Page 20 GAP Communications GAPCDR speed up programs generally write directly to the screen instead of using the BIOS. To see how the DOS window works, after setting it up, issue the following call: system("COMMAND"); This will put you in a DOS shell. You may then execute various DOS functions and get a feel for what it looks like. Be sure to type "exit" to return to your program. When you no longer need the DOS window, it is imperitive that you remove the interrupt 10 (BIOS) intercepter or your computer will hang when you exit the program. There is a fully working example of a DOS Window in the CDOOR example program. It shows how to save a portion of the screen, draw a box, set up the interrupt 10 intercepter and shell to DOS. Upon return from the shell, it will remove the DOS Window. Page 21 GAP Communications GAPCDR Variables Defines The following defines are used when calling show_mess. NO - Defined as 0 YES - Defined as 1 Ansi Variables ANSI strings contain the actual ANSI color sequences. A_BLACK - ANSI codes for Black A_BLUE - ANSI codes for Blue A_BROWN - ANSI codes for Brown A_CYAN - ANSI codes for Cyan A_GREEN - ANSI codes for Green A_MAGENTA - ANSI codes for Magenta A_RED - ANSI codes for Red A_WHITE - ANSI codes for White A_BBLACK - ANSI codes for Grey A_BBLUE - ANSI codes for bright Blue A_BCYAN - ANSI codes for bright Cyan A_BGREEN - ANSI codes for bright Green A_BMAGENTA - ANSI codes for bright Magenta A_BRED - ANSI codes for bright Red A_BWHITE - ANSI codes for bright White A_YELLOW - ANSI codes for Yellow Page 22 GAP Communications GAPCDR DOOR.SYS Variables DOOR.SYS variables are initialized while reading the DOOR.SYS file. These variables are the door programmer's connection to the BBS. Short Integers alarm - 0 = caller alarm off, 1 = on baud - DTE bps rate (unsigned) bell - 0 = page bell off, 1 = bell on color - 0 = no color, 1 = color curfiles - current files downloaded dflt_color - BBS default color digiseg - DigiBoard Memory Window digiport - DigiBoard I/O Port digichnl - DigiBoard Channel # expert - 0 = novice, 1 = expert interface - 0 = Standard, 1 = DigiBoard, 2 = INT14/EBIOS level - user's security level local - 0 = remote user, 1 = local user maxfiles - max files available minsleft - minutes left at door start multi - 1 = system is multi-user node - node number in use, 0 = single page - page length parity - actually data bits, not used port - com port being used printer - 0 = printer off, 1 = printer on realcredit - time credits from the BBS screen - 0 = screen off, 1 = screen on userbaud - remote user's bps rate (unsigned) Page 23 GAP Communications GAPCDR Long Integers curbytes - current download bytes doors_open - total doors opened downbytes - total download bytes downloads - total number of downloads maxbytes - max bytes can download mesleft - total messages left recnum - user's record number timeson - # of times on upbytes - total upload bytes uploads - total number of uploads Character Arrays bphone - user's business phone number city - user's home town event_time - event run time fname - user's first name handle - caller's Handle hphone - user's home phone number last_new - last new files scan lastdate - last date user was on lname - user's last name password - user's password subscrip - date user's subscription expires username - user's full name Page 24 GAP Communications GAPCDR Global Variables These variables are the documented, global variables (initialized and used by GAPCDR). They may be modified and/or used at the programmer's discretion. Characters chat - true if chatting with user clockon - 0 no clock, 1 display clock column - column we are at now endview - true if dont want to viewany more flag - flag that a space was pressed instatus - if doing status line noup - if 1, dont uppercase characters NS - true if in Non Stop mode redisplay - true if wants to start over usemore1 - true if showing a file view - true to use the more prompt wordwrap - column to wrap words at Short Integers base_add - base address for port irq - IRQ for port lines - # of lines currently displayed normal - current display color timecredit - any time credits user may have timeleft - time user has left Long Integers starttime - time door opened temptime - for calculating time out timenow - current time Page 25 GAP Communications GAPCDR Character Arrays anystring - global garbage collector bbs_dir - path to DOOR.SYS birthday - caller's birth date board_name - name of the BBS BS - backspace characters CRLF - carriage return/line feed characters curtime - holds the current time as a string gendir - path to the BBS gen dir maindir - path to the BBS main dir strtime - holds the time string sysname - sysop's name Structures GAP_USER user - GAP's User Record PCBSYS pcbsys - PCB's System Record PCBUSER pcbuser - PCB's User Record These structures are fully commented in the GAPCDR.H header file. Note that when utilizing the GAP user structure, all string fields are fully padded with spaces and the last position must be a 0. Page 26 GAP Communications GAPCDR Functions - Quick Reference access1 - Checks for the existence of a file. ansi - Displays ANSI color strings. backspace - Sends one or more backspaces. ckeypress - Checks for a remote or local key press. clear_scrn - Clears the local and remote screens. clr_buf - Cleare the communications receive buffer. cls - Clears the 1st 23 lines on the local screen. cls_all - Clears the entire local screen. comgetc - Gets a character from com port. comgetd - Geta a character from com port with timeout. computb - Sends a buffer of data to com port. computc - Sends a character to com port. computs - Sends a string to com port. cursoff - Turns local cursor off. curson - Turns local cursor on. do_chat - To allow sysop to chat with remote user. dtr - Toggels the DTR line on or off. dv_here - Checks for the presense of DESQView. dv_pause - Gives up remainder of time slice to DV. elap_time - Computes elapsed time. empty - Empties a string. fix_color - Modifies ANSI driver for color or mono. gapputc - Sends a character to local and remote. gapputs - Sends a string to local and remote screens. getakey - Gets one key responses. getkeyc - Gets keyboard character and scan code. get_attr - Gets startup video attribute. get_random - Returns a random number. get_string - Gets a string of characters. init_ansi - Initializes ANSI driver. init_com - Initializes Communications Port. init_door - Initializes the Door. init_port - Sets up Communications Port. iscd - Checks if there is a Carrier. leave - Shuts down door and returns to the BBS. lputc - Sends a character to local screen. lputs - Sends a string to local screen. make_sound - Makes noise on local computer. more - Checks for a full screen. nl - Sends a CR/LF to local and remote. no_carrier - Called by the Comm Routines if Carrier lost. pagesysop - Alerts sysop that the user wants to chat. pause - Sends a "Press [Any Key] To Continue" prompt. putkey - Used by chat for word wrapping. read_cnf - Reads the door configuration file. Page 27 GAP Communications GAPCDR read_doorsys - Reads DOOR.SYS. read_gapuser - Reads USERS.DAT. read_pcbsys - Reads PCBOARD.SYS. read_pcbuser - Reads PCB USERS file. read_score - Reads and displays top 10 scores. reset_port - Restores Communications Port. restore_screen - Restores a portion of the screen. rest_cbreak - Restores Ctrl-Break vector. rest_int10 - Restores BIOS vector. rts - Toggels RTS line on or off. rxempty - Checks if any characters in receive buffer. save_screen - Saves a portion of the screen. setport - Initializes Communications port. set_attr - Sets video attributes. set_cbreak - Initializes Ctrl-Break vector. set_cord - Sets up a DOS Window. set_int10 - Initializes BIOS trapper. set_status - Displays status line. show_file - Displays text files. show_mess - Displays a message. timer - Time Delay. time_credit - Gives credits for time used. time_left - Computes time remaining. trim - Trims spaces from string. update_clock - Updates status line clock. wrap_word - Wraps a word. write_gapuser - Writes USERS.DAT. write_pcbsys - Writes PCBOARD.SYS. write_pcbuser - Writes PCB USERS. write_score - Creates and maintains top 10 scores file. Functions - Detailed Reference Functions will return either a void (nothing), a short value, or a character pointer. The function descriptions will note whether or not a function is high level or low level. The high level functions are basically the only functions you will ever need to use. When necessary, they will call other functions to carry out their work. The low level functions, on the other hand, are more single purpose, and they generally require calls to other low level functions to perform the same task as one call to a high level function. Page 28 GAP Communications GAPCDR access1 ----------------------------------------------------------------- Purpose Checks for the existence of a file. short access1(char *filename); filename Full path and name of file Type High Level Description This function is used to check for the existence of a file. It works in a multi-user environment and is not affected by file sharing attributes. Return Value 0 = File exists, 1 = File not found. Example if ((access1("FILE.DAT"))) show_mess("Sorry, File does not Exist!", YES,YES); Page 29 GAP Communications GAPCDR ansi ----------------------------------------------------------------- Purpose Displays ANSI color sequences. void ansi(char *color); color Ansi color string Type High Level Description This function will send a string of ANSI escape sequences to the remote user and to the local console. The ANSI codes for the various colors are declared as global variables. If the remote or local user is in non graphics mode, the function returns immediately. Return Value None. Example ansi(A_BWHITE); // Change color to bright white Page 30 GAP Communications GAPCDR backspace ----------------------------------------------------------------- Purpose Sends one or more backspaces. void backspace(short num); num Number of backspaces to send Type High Level Description In order to actually erase a character on the screen, you must send a 3 character sequence which consists of backspace, space, backspace. This function will send as many of these 3 character sequences as you specify in the parameter list. Return Value None. Example backspace(1); // erase last character sent Page 31 GAP Communications GAPCDR ckeypress ----------------------------------------------------------------- Purpose Checks for a remote or local key press. short ckeypress(void); Type High Level Description This function will check the local keyboard as well as the communications receive buffer to see if a key is waiting to be read. It is most often used in loops that monitor keyboard timeout, time remaining, etc. Return Value 0 = no key is waiting, 1 = a key is waiting. Example c = ckeypress(); // key pressed? while(!ckeypress()) // do nothing { // until a key is pressed dv_pause() // give up time slice } Page 32 GAP Communications GAPCDR clear_scrn ----------------------------------------------------------------- Purpose Clears local and remote screens. void clear_scrn(void); Type High Level Description This routine will use the assembler routine cls to clear the first 23 lines of the local screen. If the remote caller is in non-color mode, it sends a CTRL-L to the remote screen, otherwise it sends the ANSI clear screen sequence. Return Value None. Example clear_scrn(); // clear screen Page 33 GAP Communications GAPCDR clr_buf ----------------------------------------------------------------- Purpose Clears the Communications receive buffer. void clr_buf(void); Type Low Level Description Empties the receive buffer such that any pending characters are simply ignored. Return Value None. Example clr_buf(); // clear the receive buffer Page 34 GAP Communications GAPCDR cls ----------------------------------------------------------------- Purpose Clears the first 23 lines on the local screen. void cls(void); Type Low Level Description This function will clear the first 23 lines on the local screen, thereby protecting the bottom 2 lines. Return Value None. Example cls(); // clear 1st 23 lines Page 35 GAP Communications GAPCDR cls_all ----------------------------------------------------------------- Purpose Clears the entire local screen. void cls_all(void); Type Low Level Description This function will clear the entire local screen. It is used by leave to tidy up the screen. Return Value None. Example cls_all(); // clear entire screen Page 36 GAP Communications GAPCDR comgetc ----------------------------------------------------------------- Purpose Retrieve a character from communications buffer. short comgetc(void); Type Low Level Description Checks the communications receive buffer and returns the next character, if any. Return Value Next character in buffer or -1 for no characters to read. Example c = comgetc(); // get a character from remote Page 37 GAP Communications GAPCDR comgetd ----------------------------------------------------------------- Purpose Retrieve a character from comminications buffer with delay. short comgetd(short secs); secs Number of seconds to wait Type Low level Description This function is the same as comgetc, except that if there are no characters in the receive buffer, it will wait for the number of seconds you specify. Comgetd is fully DESQview aware and will give up the program's time slice while waiting for incoming characters. Return Value Next character in buffer or -10 for time-out (no characters to read). Example if ( (comgetd(2)) == -10) // wait for 2 seconds ; // nothing happening Page 38 GAP Communications GAPCDR computb ----------------------------------------------------------------- Purpose Sends a buffer of data out the communications port. void computb(char *buffer,short len); buffer Buffer containing data to send len Number of bytes to send Type Low Level Descripton This function will send a user suplied buffer of len bytes out the communications port, one byte at a time. It will not return until all characters have been sent. Return Value None. Example computb(buffer,100); // Send 100 bytes of data Page 39 GAP Communications GAPCDR computc ----------------------------------------------------------------- Purpose Sends a single character out the communications port. void computc(unsigned char ch); ch Character to send Type Low Level Description Will send a single character out the communications port. Return Value None. Example computc('A'); // Send a character Page 40 GAP Communications GAPCDR computs ----------------------------------------------------------------- Purpose Sends a string of characters out the communications port. void computs(char *str); str String to send Type Low Level Description Will send a string of characters out the communications port. Note that unlike computb, the number of bytes to send is determined by the length of the string. Therefore this function stops sending characters when it encounters the null byte. Return Value None. Example computs("Send this string"); // send a string Page 41 GAP Communications GAPCDR cursoff ----------------------------------------------------------------- Purpose Turns the local cursor off. void cursoff(void); Type Low Level Description This function is used to turn the cursor on the local monitor off. Return Value None. Example cursoff(); // turn the cursor off curson ----------------------------------------------------------------- Purpose Turns the local cursor on. void curson(void); Type Low Level Description This function is used to turn the cursor on the local monitor on. Return Value None. Example curson(); // turn the cursor on Page 42 GAP Communications GAPCDR do_chat ----------------------------------------------------------------- Purpose To allow sysop to chat with remote user. void do_chat(void); Type High Level Description This function allows a one on one chat with a re- mote user. If the caller is in graphics mode, the sysop's key presses will be displayed in green and the remote user's key presses will be displayed in white. Text will automatically wrap at column 76. To exit chat, press either the ESC key or type a CTRL-X. Note that the user may also send these characters to end chat. The user will receive full credit for the time spent chatting with the sysop. However, this function will not update the BBS system file so it is possible that the user may be logged off (with an out of time message) when he/she returns to the BBS. Return Value None. Example do_chat(); // chat with caller empty(response,1); // initialize string get_string(response); // get a string if (response[0] == 'P') // paging sysop do_chat(); // chat with sysop Page 43 GAP Communications GAPCDR dtr ----------------------------------------------------------------- Purpose Toggle the DTR line on and off. void dtr(short how) how 0 = Turn DTR off. 1 = Turn DTR on Type Low Level Description This routine is used to turn the DTR line of the communications port on or off. Turning DTR off while there is a carrier will cause the modem to drop carrier on the remote caller. In order to send commands to the modem, DTR needs to be on. Return Value None. Example dtr(1); // turn DTR on computs("ATZ"); // reset the modem Page 44 GAP Communications GAPCDR dv_here ----------------------------------------------------------------- Purpose Checks to see if the program is running under DESQview. short dv_here(void); Type Low Level Description This function should generally be called when a program first starts (before any screen output is performed). It makes a special DOS call to see if DESQview is installed. If so, it sets an internal flag indicating the presense of DV. If the program is detected to be running under DESQview then all "do nothing" loops (those loops that are looking for something to do but because they are waiting for keyboard or com input, are basically taking up computer time doing nothing), will give up the remainder of their time slice after they figure out there is nothing for them to do. In addition, because the built in ANSI driver writes directly to the screen, if DESQview is present, the driver will instead write to DV's video shadow buffer. This function is automatically called by init_door so it is not necessary to call it again. Return Value DESQview version number or 0 for not installed. Example if ( (dv_here())) show_mess("We are running under DESQview!", NO,YES); Page 45 GAP Communications GAPCDR dv_pause ----------------------------------------------------------------- Purpose Give up remainder of time slice to DESQview. void dv_pause(void); Type Low Level Description If DESQview is installed, this function will make a call to DV such that DV will immediately switch to another task. Note that dv_here must be called at the beginning of the program since it sets an internal variable that this function checks to see if DESQview is running. You should use this function inside of all "do nothing" loops. Return Value None. Example time (&temptime); // start timer while (!getakey()) // until a key is pressed { elap_time(); // check time remaining dv_pause(); // give up time slice } Page 46 GAP Communications GAPCDR elap_time ----------------------------------------------------------------- Purpose Computes elapsed time while waiting for keyboard input. void elap_time(void); Type High Level Description This function is used in loops that await a key- board response. Prior to entering the loop, the variable called temptime should be initialized with the current time. Once inside the loop, this function should be called to keep track of the elapsed time. If there is no keyboard response within 4 minutes, the user will be logged off. Return Value None. Example time (&temptime); // start timer while (!getakey()) // until a key is pressed { elap_time(); // check time remaining dv_pause(); // give up time slice } Page 47 GAP Communications GAPCDR empty ----------------------------------------------------------------- Purpose Empties a string to all spaces. void empty(char *str,short len); str The string to be emptied len Number of bytes to clear Type High Level Description Before using the string input routine, get_string, the string must first be cleared to the maximum number of bytes allowed to be input. Empty clears the string to all spaces and adds a null byte at the end. The null byte is not counted in the len parameter. Return Value None. Example char instr [11]; empty(instr,10); // empty the string get_string(instr); // get up to 10 characters // of input Page 48 GAP Communications GAPCDR fix_color ----------------------------------------------------------------- Purpose Modify ANSI driver according to user's color. void fix_color(void); Type Low Level Description The ANSI driver is self modifying, meaning that depending upon the color preference of the user, it will adjusts its code accordingly. This function is called by init_ansi and should never need to be called by the programmer directly unless the programmer provides a menu choice whereby a caller may toggle his/her color mode on and off. In such a case, you would immediately need to call fix_color so that the ANSI driver can adjusts itself. The caller's color preference is stored in the variable color where 0 means no color, and 1 means color. Return Value None. Example show_mess("Toggle Color",NO,NO); // part of menu empty(response,1); // clear string get_string(response); // get response to menu if (response[0] == 'C') // wants to toggle color { if (color) color = 0 else color = 1; fix_color(); // fix up ANSI driver } Page 49 GAP Communications GAPCDR gapputc ----------------------------------------------------------------- Purpose Sends a single character to local and remote. void gapputc(short ch); ch Character to send Type Low Level Description This is one of the main output routines that is used internally by GAPCDR. It is part of the ANSI driver. It will send a single character to the local screen and if a remote caller is on, will send the character to the communications port as well. Return Value None. Example gapputc('A'); // display a character while ( (c = getakey()) == 0) // wait for keypress dv_pause(); // give up time slice gapputc(c); // display character Page 50 GAP Communications GAPCDR gapputs ----------------------------------------------------------------- Purpose Sends a string of characters to local and remote. void gapputs(char *str); str String to send Type Low Level Description This is one of the main output routines that is used internally by GAPCDR. It is part of the ANSI driver. It will send a string of characters to the local screen and if a remote caller is on, will send the string to the communications port as well. If a caller is in mono mode, the ANSI driver will strip any ANSI sequences from the string. This allows you to "colorize" your strings with ANSI codes and not have to worry if the caller has his color setting turned on. This routine is much faster than show_mess (in fact, this is the function that show_mess calls), but it does not provide for ringing the bell or automatically sending a carriage return and line feed after the string. You can however embed these characters into the string. It is suggested that you not embed the bell character into the string since the sysop may have the alarm toggled off and may not appreciate the computer making noise when he/she doesn't want it to. Return Value None. Example gapputs("This is a string of characters"); // this example embeds the CR/LF pair at the beginning // and end of the string gapputs("\r\nThis is a string\r\n"); Page 51 GAP Communications GAPCDR getakey ----------------------------------------------------------------- Purpose Gets one key responses short getakey(void); Type High Level Description This is the main keyboard input routine. It is called by get_string as well as any keyboard polling loops. It checks the receive buffer as well as the local keyboard for a key press. If one is not found it returns 0. The character input is not echoed. Since 99% of all keyboard input comes from this routine, it checks for time remaining, keyboard time-out, as well as special sysop function keys. The timeleft variable is updated by this routine. This is the variable you would normally use in a prompt such as: [20 mins left] Main Command : Return Value ASCII code for the key pressed or 0. Example c = getakey(); // get a character Page 52 GAP Communications GAPCDR getkeyc ----------------------------------------------------------------- Purpose Gets keyboard character and scan code. short getkeyc(void); Type Low Level Description This is the main keyboard input routine which is called internally by getakey. It returns the keyboard character or if the key struck was an extended key, it will return a unique code. These codes are defined in GAPSTRUC.H as F1, Home, etc. This function always waits for a keypress so it should not be called unless you know there is a key waiting. Return Value ASCII code for the key pressed or a unique code for extended keys. Example keyc = getkeyc(); // get a keyboard character Page 53 GAP Communications GAPCDR get_attr ----------------------------------------------------------------- Purpose Retrieves the current screen color. void get_attr(void); Type Low Level Description This function is used at the very start of a program to "remember" the screen color. It stores the color in a special location so that the screen attributes can be restored by the DOS Window routines. You do not need to call this routine if you have no plans to use the DOS Window. Return Value None. Attribute is stored in an internal location. Example get_attr(); // Remember screen attributes Page 54 GAP Communications GAPCDR get_random ----------------------------------------------------------------- Purpose Gets a random number. short get_random(short low,short high); low Lowest number acceptible high Highest number acceptible Type High Level Description This routine is provided because it is much easier to use and understand than the C library routine (which drags in the floating point library). Provide as parameters, two integers. The first parameter is the lowest number you will accept as a random number, and the second parameter is the highest random number you will accept. The function will return a random integer between the range specified (low and high are included in the range of numbers). It is not necessary to seed the random number generator as this is done automatically for you during program initialization. Return Value A random number between range specified. Example rndnum = get_random(1,10); // get a random num Page 55 GAP Communications GAPCDR get_string ----------------------------------------------------------------- Purpose Gets a string of characters. void get_string(char *string); string Storage for input characters Type High Level Description This is the main input routine. It will get a string from either the remote user or the local keyboard. The string passed will be set to the characters received. The length of the input string is determined by the length of the string passed. Before calling, you must initialize the passed string with spaces. The number of spaces in the string determines the number of characters allowed to be input. If a user attempts to type more characters than allowed, the cursor will not move pass the end of the string. Input ends when the Enter key is pressed. To initialize the string, use the empty function. WARNING : It is extremely important that the passed string be initialized. Failure to set the string to spaces, will cause unpredictable results! This function does not return a new string con- taining the keyboard input. Instead, it modifies the string you pass to it in the parameter list. The string will be stripped of any trailing spaces. Get_string automatically uppercases the string. If you wish to disable this feature, set the variable noup to 1 just prior to calling the function, and then set it back to 0 when the function returns. Get_string will automatically check for keyboard activity so it is not necessary for you to do so. Return Value None Page 56 GAP Communications GAPCDR Example get_string(instr); // get a string char instr [20]; // First initialize the string. In this case we will // accept up to 10 characters empty(instr,10); // initialize string get_string(instr); // get string Page 57 GAP Communications GAPCDR init_ansi ----------------------------------------------------------------- Purpose Initialize ANSI driver. void init_ansi(void); Type Low Level Description This routine is called by init_door so it is not necessary for you to call it again. It sets up the ANSI driver so that it knows the sysop's default color, the current cursor position, etc. Return Value None. Example init_ansi(); // Initialize ANSI driver Page 58 GAP Communications GAPCDR init_com ----------------------------------------------------------------- Purpose To configure the communications port. void init_com(void); Type High Level Description This function takes the information provided by DOOR.SYS and makes a call to setport to set up the communications port and receive buffer. It is called internally by init_door. If there is an error setting up the port, init_com will exit the program. Return Value None. Exits on Error. Example init_com(); // Initialize com port Page 59 GAP Communications GAPCDR init_door ----------------------------------------------------------------- Purpose Initializes the GAPCDR functions. void init_door(void); Type High Level Description This routine must be called immediately after calling read_cnf. It initializes the door, opens and reads system files, initializes the com port, initializes global variables and in general, makes sure that all of the files required for operation are present. If an error occurs while trying to initialize, the function will display an error message and end the program. Return Value None. Exits on error. Example fp = read_cnf("DOOR.CNF"); // read cnf file init_door(); // init the door fclose(fp); // close configuration file Page 60 GAP Communications GAPCDR init_port ----------------------------------------------------------------- Purpose Initialize port to baud, data, and parity. init_port(short parity, short data); parity 0 = None, 1 = Even data 6,7,or 8 data bits Type Low Level Description Sets the communications port to the parity and data bits passed as parameters. The baud rate is contained in a global variabled called baud. The port number (where COM 1 equals port 0) is contained in a global variabled called port. Return Value 0 = Successful, 1 = Error. Example init_port(0,8) // Initialize to N,8,1 Page 61 GAP Communications GAPCDR iscd ----------------------------------------------------------------- Purpose Check for Carrier on the Communications Port. short iscd(void); Type Low Level Description This function allows you to test the communications port for a remote carrier signal. Note that carrier checking is performed automatically by the communications routines so it is not necessary for you to explicitly check for carrier unless you have a need to override the default actions taken. Return Value Returns 0 if there is no carrier and 1 if there is a carrier. Example if ( !iscd()) // is there a carrier? leave(99); // nope, lets quit Page 62 GAP Communications GAPCDR leave ----------------------------------------------------------------- Purpose Exits the program. void leave(short code); code Exit code to terminate with Type High Level Description When the program terminates, it must call this function to end. This is the only proper exit from the door. It is of vital importance to end your program through this function so that the interrupt service routines that are installed at door beginning can be removed. Return Value None. Example leave(0); // Exit the program Page 63 GAP Communications GAPCDR lputc, lputs ----------------------------------------------------------------- Purpose To display a character or string of characters on the local screen. void lputc(char ch); ch Character to display void lputs(char *str); str String to display Type Low Level Description Like gapputc and gapputs, these functions display either a single character or a string of characters, however the characters are not simultaneously sent to the communications port as well. These functions override the color mode of the caller and allow you to send ANSI color to the local screen even if the caller does not have his color flag turned on. Return Value None. Example lputs("This is a string"); // Send string Page 64 GAP Communications GAPCDR more ----------------------------------------------------------------- Purpose Checks for a full screen and issues a More Prompt. void more(void); Type High Level Description This is an internal routine that is called by the character output functions. It issues a more prompt if the number of lines displayed reaches the user's page length. Return Value None. Page 65 GAP Communications GAPCDR nl ----------------------------------------------------------------- Purpose Sends a Carriage Return and Line Feed to local and remote. void nl(short lines); lines Number of New Lines to send Type High Level Description To send a blank line, call this routine with the number of blank lines you wish to send. Return Value None Example nl(2); // send two blank lines Page 66 GAP Communications GAPCDR no_carrier ----------------------------------------------------------------- Purpose Used by the Communications routines. void no_carrier(void); Type High Level Description Internal routine that is called when there is a loss of carrier. Displays a message to the local screen and then calls leave to terminate the program. This function must not be removed from GAPCDR. You may modify it to change the default actions that are taken, but the communications routines must have access to it if there is a loss of carrier. Return Value None. Example Page 67 GAP Communications GAPCDR pagesysop ----------------------------------------------------------------- Purpose Alerts sysop that user wants to chat. void pagesysop(void); Type High Level Description Allows the programer to provide the user with a Page Sysop command. The page lasts for 30 seconds and can be aborted by typing CTRL-K. If the sysop's page bell is on, the sysop's speaker will also sound. To answer the page, the sysop should press CTRL-F10. Return Value None. Example pagesysop(); // tell sysop empty(response,1); // initialize string get_string(response); // get a response if (response[0] == 'P') // wants to chat pagesysop(); // tell sysop Page 68 GAP Communications GAPCDR pause ----------------------------------------------------------------- Purpose Sends a "Press [Any Key] To Continue" prompt. void pause(void); Type High Level Description This function sends a pause prompt and waits for a key press. Return Value None. Example pause(); // display pause prompt Page 69 GAP Communications GAPCDR putkey ----------------------------------------------------------------- Purpose Used by chat routines to keep track of word wrapping. void putkey(short ch); ch Character to send Type High Level Description This is the main output routine for the chat functions. It keeps track of the current column, and decides when it is time to wrap a word. Return Value None. Example Page 70 GAP Communications GAPCDR read_cnf ----------------------------------------------------------------- Purpose Reads the door configuration file. FILE *read_cnf(char *path); path Full path and name of configuration file Type High Level Description Opens the configuration file for the current door. Normally the passed parameter is the name of the door with a .CNF extension (it is assumed that the file is in the same directory as the door program). If an error occurs, the program ends immediately. WARNING : The first eight lines of this configura- tion file belong to the GAPCDR interface module. You are free to use the information, but the in- formation contained in the first eight lines must conform exactly to the following specifications. The first line of this file is the full drive and path to the BBS default directory. This is the directory where the BBS created the DOOR.SYS file. The second line is the name of the BBS. The third line is the IRQ for the port, and the fourth line is the Base Address for the port. If the sysop uses Com Ports other than 1 or 2, then he must enter the appropriate IRQ and BASE address so that GAPCDR can properly open the port. If Com ports 1 or 2 are used, then a 0 may be entered on both of these lines. The fifth line is the Communications Port Interface and must be either STANDARD, DIGIBOARD, or INT14/EBIOS. The sixth line is the DigiBoard Memory Window. The seventh line is the DigiBoard I/O Port Address. The eighth line is the DigiBoard Channel Number. It is the responsibility of the door author to describe the format of these eight lines to the end user. If your door program requires no configuration parameters of its own, you can simply distribute a sample configuration file with these eight lines already in it. Page 71 GAP Communications GAPCDR GAPCDR will not close this file after reading the first four lines. It leaves the file open for the programmer's use. Remember that you assign a FILE pointer to the return value so that you may access the file. If your door does require certain configuration parameters, have your users place the parameters in the file starting with line 9. If you use a set up program, be sure that your set up program writes the first eight lines as specified. After you have called read_cnf and init_door, if you have any configuration options in the configuration file, you should use the stream input routines to read those options. Then fclose the file using the FILE pointer returned. Even if you have no options to read, you must close the file. WARNING : You must call this routine before using any of the GAPCDR functions. After calling this routine, you must call init_door. Return Value FILE pointer. Example FILE *fp; // File pointer fp = read_cnf("TOURIST.CNF"); // read cnf file fclose(fp); // close the file init_door(); // init the door Page 72 GAP Communications GAPCDR read_doorsys ----------------------------------------------------------------- Purpose Reads the DOOR.SYS universal door interface file. short read_doorsys(void); Type High Level Description Internal routine called by init_door. Reads the DOOR.SYS file and initializes any global variables that depend on the information in that file. Return Value 0 = no error, 1 = error. Example c = read_doorsys(); Page 73 GAP Communications GAPCDR read_gapuser ----------------------------------------------------------------- Purpose Reads the GAP Communications USERS.DAT file. short read_gapuser(char *path); path Full path and name of the USERS file Type High Level Description Reads the user record of the current user in the GAP USERS.DAT file. The record is read into a structure variable called gapuser. You must supply the path and name to the base part of the User file. GAP stores the name of the User file in the GAPBBS.CNF file (which you must read yourself). Read_gapuser will add the .DAT extension. Return Value 0 = no error, 1 = error. Example c = read_gapuser(userpath); Page 74 GAP Communications GAPCDR read_pcbsys ----------------------------------------------------------------- Purpose Reads the PCBOARD.SYS file. short read_pcbsys(void); Type High Level Description Reads the PCBOARD.SYS system file. The record is read into a structure variable called pcbsys. Return Value 0 = no error, 1 = error. Example c = read_pcbsys(); Page 75 GAP Communications GAPCDR read_pcbuser ----------------------------------------------------------------- Purpose Reads the PCB USERS file. short read_pcbuser(char *path); path Full path and name of the USERS file Type High Level Description Reads the user record of the current user in the PCB USERS file. The record is read into a structure variable called pcbuser. You must supply the path and name to the User file. PCB stores the path\name of the User file in the PCBOARD.DAT file (which you must read yourself). Return Value 0 = no error, 1 = error. Example c = read_pcbuser(userpath); Page 76 GAP Communications GAPCDR read_score ----------------------------------------------------------------- Purpose Reads the score file and displays the results. short read_score(char *datfile,char *message); datfile Path and name of data file to read message Message to display Type High Level Description This function will read the scoreboard data file for your door (if any) and display the results. You pass as parameters the name of the data file to read, and a message to display at the top of the scoreboard. The message could be something like "Top 10 Players". Return Value 0 = scores read, 1 = no scores to read. Example read_score("TOURIST.DAT","Top 10 Tourists"); if (read_score("TOURIST.DAT","Top 10 Tourists")) { nl(1); ansi(BWHITE); show_mess("No one's made it Yet!",NO,YES); } Page 77 GAP Communications GAPCDR reset_port ----------------------------------------------------------------- Purpose Restores the Communications port. void reset_port(void); Type Low Level Description This function must be called prior to exiting the program. It restores the interrupt vector used by the communications routines. It is called internally by leave so it is not necessary for you to explicitly invoke it. Return Value None. Example reset_port(); // Restore communications port Page 78 GAP Communications GAPCDR restore_screen ----------------------------------------------------------------- Purpose Restores a previously saved portion of the screen. void restore_screen(short topr, short topc, short botr, short botc, unsigned short memseg); topr Top row of screen topc Top left column of screen botr Bottom row of screen botc Bottom right column of screen memseg Segment of buffer to save to Type Low Level Description This function allows you to restore a previously saved portion of the screen. You supply the top row and column and the bottom row and column co- ordinates of the rectangle. All co-ordinates are 0 based. The memseg is the segment address of the buffer that a previous call to save_screen saved the video contents to. Return Value None. Example restore_screen(3,8,16,71,dseg); Page 79 GAP Communications GAPCDR rest_cbreak ----------------------------------------------------------------- Purpose Restores the Ctrl-Break vector. void rest_cbreak(void); Type Low Level Description This function must be called prior to exiting the program. It restores the interrupt vector used by the Ctrl-Break routine. It is called internally by leave so it is not necessary for you to explicitly invoke it. Return Value None. Example rest_cbreak(); // restore Ctrl-Break vector Page 80 GAP Communications GAPCDR rest_int10 ----------------------------------------------------------------- Purpose Restores the interrupt 10 (BIOS) vector. void rest_int10(void); Type Low Level Description When setting up an interrupt 10 BIOS trap to protect a DOS Window, this function must be called when it is no longer necessary to protect a portion of the screen. Return Value None. Example See the example for set_cord. Page 81 GAP Communications GAPCDR rts ----------------------------------------------------------------- Purpose Toggle the RTS line on and off. void rts(short how) how 0 = Turn RTS off. 1 = Turn RTS on Type Low Level Description This routine is used to turn the RTS line of the communications port on or off. Turning RTS off (providing the modem supports hardware handshaking) tells the modem to stop sending data to the computer. It is typically toggled off while writing a buffer of data to a disk. Return Value None. Example rts(0); // Turn RTS off Page 82 GAP Communications GAPCDR rxempty ----------------------------------------------------------------- Purpose To check if there are any characters in the receive buffer. short rxempty(void); Type Low Level Description This function checks the communications receive buffer to see if there are any characters waiting to be read. Return Value Returns 1 if buffer is empty, 0 if there are characters waiting to be read. Example while (rxempty()) // nothing happening dv_pause(); // give up time slice Page 83 GAP Communications GAPCDR save_screen ----------------------------------------------------------------- Purpose Saves a portion of the screen. void save_screen(short topr, short topc, short botr, short botc, unsigned short memseg); topr Top row of screen topc Top left column of screen botr Bottom row of screen botc Bottom right column of screen memseg Segment of buffer to save to Type Low Level Description This function allows you to save a rectangular portion of the screen. You supply the top row and column and the bottom row and column co-ordinates of the rectangle. All co-ordinates are 0 based. The memseg is the segment address of a buffer to save the video contents to and assumes your buffer was allocated by DOS (i.e., the offset portion of the buffer begins at 0). Return Value None. Example unsigned short dseg; dos_allocatemem(114,&dseg); // get some memory save_screen(3,8,16,71,dseg); // save contents of video Page 84 GAP Communications GAPCDR setport ----------------------------------------------------------------- Purpose Initialize the Communications Port. short set_port(short bufsize, short irq, short base); bufsize Size of Receive buffer irq Port IRQ to use base Port Base Address to use Type Low Level Description This is the port initialization routine that is called by init_com. Bufsize is the size of the receive buffer to set up. Set_port will allocate memory based upon this size. Typical values are from 1200 to 4096 bytes. Note that the bufsize argument is ignored when using the Borland compiler. This is because Borland does not provide a memory allocation routine that allocates memory in the near heap (irregardless of memory model). For Borland, the bufsize is fixed at 2048 bytes. IRQ is the Interrupt Request number to use for the port and Base Address is the address where the port is located. The Port number is a global variable that is set when reading DOOR.SYS. Ports start with 0, where 0 equals COM 1, 1 equals COM 2, etc. For COM 1 and COM 2, you may simply pass 0 as the IRQ and Base address since the defaults for these ports will be used. Return Value 0 = successful, 1 = error encountered. Example // set up the port with a buffer size of 2k, using COM 1 port = 0; if (setport(2048, 0, 0)) exit(1); Page 85 GAP Communications GAPCDR set_attr ----------------------------------------------------------------- Purpose Sets the video color attributes. void set_attr(unsigned char forg, unsigned char back); forg Foreground Color (0-15) back Background Color (0-7) Type Low Level Description This function is used just prior to invoking a DOS Window so that the window colors can be set. Return Value None. Example See the example for set_cord. Page 86 GAP Communications GAPCDR set_cbreak ----------------------------------------------------------------- Purpose Initializes the Ctrl-Break vector. void set_cbreak(void); Type Low Level Description To trap Ctrl-C and Ctrl-Break, this function should be called to set up an interrupt service routine to trap these two keys. It is imperitive that the program not exit before calling rest_cbreak so that the interrupt vector can be restored. Leave does this for you automatically. Return Value None. Example set_cbreak(); // set up Ctrl-Break ISR Page 87 GAP Communications GAPCDR set_cord ----------------------------------------------------------------- Purpose Set up a DOS Window. void set_cord(unsigned char topr, unsigned char topc, unsigned char botr, unsigned char botc); topr Top left row topc Top left column botr Bottom row botc Bottom right column Type Low Level Description This function sets the window co-ordinates for a DOS Window. Using this function in combination with set_int10 allows you to set up a window into which all local screen output will be directed. Topr and topc are the top left corner of the window and botr and botc are the bottom right corner of the window. All co-ordinates are 0 based. Return Value None. Example _dos_allocmem(114,&dseg); // get some memory save_screen(3,8,16,71,dseg); // save a part of screen set_int10(); // set up BIOS trap set_cord(4,9,15,70); // tell it what to protect set_attr(14,1); // Yellow on Blue cls_all(); // clear the window system("COMMAND"); // go to DOS rest_int10(); // restore vector restore_screen(3,8,16,71,dseg); // restore screen _dos_freemem(dseg); // free memory Page 88 GAP Communications GAPCDR set_int10 ----------------------------------------------------------------- Purpose Set up an interrupt 10 (BIOS) trapper. void set_int10(void); Type Low Level Description This function intercepts the Interrupt 10 vector so that it can trap calls to the BIOS video output routines. It is used in conjunction with set_cord to set up a portion of the screen into which all video output through the BIOS will be directed. If a console driver other than CON or ANSI.SYS is used that writes directly to the screen, this function will not work. Return Value None. Example See the example for set_cord. Page 89 GAP Communications GAPCDR set_status ----------------------------------------------------------------- Purpose Displays and updates the sysop status line. void set_status(short how); how 0 = set the status line 1 = update the status line 4 = show other user stats Type High Level Description Displays or updates the sysop status line. Return Value None. Example set_status(0); // display status line Page 90 GAP Communications GAPCDR show_file ----------------------------------------------------------------- Purpose Displays a text file. void show_file(char *filename); filename Full path and name of file to display Type High Level Description Many door programs have welcome, news, exit, help and other files to show to the user at various points in the program. This is the function that allows you to do that. To display a file to the user, call the function with the full drive\path\filename of the file to display. If you have color and non-color versions of files pass the name of the non-color version as this function will automatically append a "G" to the filename if the user is in color mode. In fact, this function will always try to find a file with a "G" appended to the end of the name (if the user is in color mode) before it looks for the actual file by the name you specified. If you pass "WELCOMEG" to this function and the user is in color mode, it will first try to find a file with the name of "WELCOMEGG". Pressing CTRL-K or CTRL-X will abort any file display. REMEMBER : If you have both color and non-color versions of the same files, pass the name of the non-color version. Also, the actual disk files must be named in such a way that they have no file extension and the color version ends with a "G". Return Value None. Example show_file("WELCOME"); // display welcome file Page 91 GAP Communications GAPCDR show_mess ----------------------------------------------------------------- Purpose Displays a message. void show_mess(char *message,short bell, short newline); message Message to display. bell YES or NO to ring the bell. newline YES or NO to issue a CR/LF after message. Type High Level Description This is the main string output function for GAPCDR. Under most circumstances, this is the only function that you would call to display output to the user. Return Value None Example show_mess("This is a message!",NO,YES); // the first show_mess displays the string and leaves the // cursor on the same line. The second displays the // string, rings the remote user's bell, and drops the // cursor to the next line. nl(1); show_mess("Are you ready? (Y/N) : ",NO,NO); empty(response,3); get_string(response); if (response[0] == 'Y') // begin whatever it is you want to begin else show_mess("Too Bad!",YES,YES); Page 92 GAP Communications GAPCDR timer ----------------------------------------------------------------- Purpose Pauses for the number of "ticks" specified. void timer(short ticks); ticks Number of timer ticks to pause. Type High Level Description This function allows you to pause all processing for the specified number of ticks. It is in- sensitive to processor speed. The function simply delays the number of "ticks" indicated by the passed parameter. Each tick is 1/18 of a second (or 55 miliseconds). Return Value None. Example timer(18); // pause for 1 second Page 93 GAP Communications GAPCDR time_credit ----------------------------------------------------------------- Purpose Issues timecredits to user. void time_credit(short flag); flag 1 = start timer 0 = end timer Type High Level Description This is basically an internal routine called by chat and sysop shell to DOS so that the user is not penalized for time used. It updates a global variable called timecredit. Timecredit is used in the calculations that determine the user's time remaining. If you wish to use this feature in your own rou- tines, prior to entering your routine, call time_credit with a 1 and it will start the timer. When your routine is finished, call time_credit with a 0 and the timer will stop. The variable timecredit will be updated with the elapsed time. Return Value None. Example time_credit(1); // start the timer time_credit(1); // start the timer do_chat(); // chat with user time_credit(0); // stop the timer Page 94 GAP Communications GAPCDR time_left ----------------------------------------------------------------- Purpose To compute the user's time remaining. void time_left(void); Type High Level Description This is the function that is called by the input and output routines to compute the user's time remaining. It is not necessary for the programmer to call this routine directly. A global variable called timeleft will be updated with each call. This variable may be used in prompts that display the user's remaining time. As long as all input/output is performed thru calls to the GAPCDR library, the timeleft variable will always be current. Return Value None. Example time_left(); // calculate time remaining Page 95 GAP Communications GAPCDR trim ----------------------------------------------------------------- Purpose Trims spaces from the end of NULL terminated strings. char *trim(char *string); string String containing trailing spaces Type High Level Description This function will remove any spaces from the end of a string. It modifies the passed string. Return Value Pointer to the string without the spaces. Example trim(username); // get rid of spaces Page 96 GAP Communications GAPCDR update_clock ----------------------------------------------------------------- Purpose Updates the status line clock. void update_clock(void); Type High Level Description Internal routine to update the status line clock. Return Value None. Example Page 97 GAP Communications GAPCDR wrap_word ----------------------------------------------------------------- Purpose To wrap a word during sysop chats. void wrap_word(void); Type Low Level Description Internal function called by putkey to wrap words. Return Value None. Example Page 98 GAP Communications GAPCDR write_gapuser ----------------------------------------------------------------- Purpose Updates the user record in GAP's USERS.DAT file. short write_gapuser(char *path); path Full path and name of Users File Type High Level Description This function allows you to update any variables in the GAP USERS.DAT file for the current user. You must first read the user record before you can write to it. You must pass the path and name of the Users file. The name is obtained by reading GAPBBS.CNF. Write_gapuser will add the .DAT extension. WARNING : The GAP USERS.DAT file contains strings that are fully padded with spaces. If you modify any of these strings, you MUST make sure that the string is fully padded with spaces and that the NULL character is placed in the last string posi- tion. WARNING : The indexes for the user file consists of the user's last name and first name, user's level, and user's handle. Do not under any circumstances modify either of these four fields. Doing so will cause corruption of the Index file. Return Value 0 = no error, 1 = error. Page 99 GAP Communications GAPCDR Example c = write_gapuser(userpath); // allow user to change city and state c = read_gapuser(userpath); if (c == 0) { show_mess("Enter City/State : ",NO,NO); empty(city,29); // clear string get_string(city); // get response if (city[0] != 0) // if something entered { strcpy(user.city,city); // copy it pad(user.city,29); // pad it with spaces c = write_gapuser(userpath); // update user record if (c == 0) show_mess("Saved new City",NO,YES); } } Page 100 GAP Communications GAPCDR write_pcbsys ----------------------------------------------------------------- Purpose Updates the PCBOARD.SYS file. short write_pcbsys(void); Type High Level Description This function allows the programmer to update the PCBOARD.SYS File. You must first read the file before you write to it and you should not use this function unless you know that your program is running with PCB as the host system. Return Value 0 = no error, 1 = error. Example c = write_pcbsys() // write the file Page 101 GAP Communications GAPCDR write_pcbuser ----------------------------------------------------------------- Purpose Updates the PCB USERS file. short write_pcbuser(char *path); path Full path and name to the Users file Type High Level Description This function allows the programmer to update the PCB USERS File. Do not use unless you know your program is running under a PCB host system. You must first read the user record before you can write to it. You must pass the path and name of the Users file. The name is obtained by reading PCBOARD.DAT. Return Value 0 = no error, 1 = error. Example c = write_pcbuser(); // write the file Page 102 GAP Communications GAPCDR write_score ----------------------------------------------------------------- Purpose Creates and maintains a scoreboard. void write_score(char *filename,long score); filename Path and name of data file to write to score Score to write Type High Level Description This function will create and maintain a scoreboard of the top ten players. You pass it two parameters. The first is a string containing the name of the data file to create/maintain. The second is a long unsigned integer containing the score to write. The user's name and the current date are already known. If the sysop is in the door at the time, the function will simply return and not write a score. The scores will automatically be sorted in decreasing order by the highest score. If you wish to use this routine but your points are kept as shorts instead of longs, simply cast the second parameter to an unsigned long. Return Value None. Example short points; points = 1000; write_score("TOURIST.DAT,(unsigned long) points); Page 103 GAP Communications GAPCDR Index Access1 27, 29 Alarm 23 Ansi 27, 30 Ansi driver color 7, 49, 51, 64 external 18, 20 initializing 11, 58 internal 7, 12, 49 ANSI variables 8, 22 Anystring 26 Backspace 26, 27, 31 Base address 9, 15, 25, 71, 85 Base_add 25, 71, 85 Batch file 16 Baud 18, 19, 20, 23, 61 Baud rate 6, 18, 19, 20, 23, 61, 85 BBS default directory 26, 71 name 26 system files 14, 26, 74, 75, 76, 99, 101, 102 Bbs_dir 26, 71 Bell 23, 92 Birthday 26 Board_name 26 Bphone 24 BS 26 Business phone number 24 Caller alarm 23 Caller's birth date 26 Carriage return 26 Carrier 18, 19, 62, 67 Characters sending to com port 27, 40 sending to local & remote 27, 50 sending to local screen 27, 64 Chat 17, 25, 43, 70 Chatting with user 25 City 24 Ckeypress 27, 32 Clear_scrn 27, 33 Clockon 25, 97 Clr_buf 27, 34 Cls 27, 33, 35 Cls_all 27, 36 Color 7, 20, 23, 25, 30, 49, 51, 54, 64, 86 Page 104 GAP Communications GAPCDR Column 25 Comgetc 20, 27, 37 Comgetd 20, 27, 38 Communications advanced applications 18 base address 9, 15, 25, 71, 85 baud rates 6, 18, 19, 20, 23, 85 carrier 18, 19, 62, 67 configuration file 9 DTR 20 FIFO buffers 6 Functions clr_buf 27, 34 comgetc 27, 37 comgetd 27, 38 computb 27, 39 computc 27, 40 computs 27, 41 dtr 27, 44 init_port 19, 20, 27, 61 iscd 27, 62 no_carrier 27, 67 reset_port 19, 28, 78 rts 28, 82 rxempty 28, 83 setport 19, 28, 85 initializing 19, 59, 60, 61, 85 input 20, 37, 38, 83 interrupt 11, 19, 63, 78 IRQ 9, 15, 25, 71, 85 output 20, 39, 40, 41 port 11, 12, 18, 23, 71, 85 Compilers compiling & linking 12 cputs 12 floating point 8, 13, 55 function calling 13 goto 13 header files 8, 53 printf 12 supported 8 Compiling 12 Computb 27, 39 Computc 20, 27, 40 Computs 20, 27, 41 Configuration file 9, 11, 15, 16, 71 format 9, 15 Control characters 8 Page 105 GAP Communications GAPCDR editor 8 Cputs 12 CRLF 26, 51 Ctrl-Break handler 11, 80, 87 Curbytes 24 Curfiles 23 Current display color 25 Current download bytes 24 Current files downloaded 23 Current time 25 Cursoff 27, 42 Curson 27, 42 Cursor 27, 42 Curtime 26 Date user's subscription expires 24 Default color 23 Delaying 93 DESQview 19, 27, 32, 38, 45, 46, 47 Dflt_color 23 Display clock 25 Display color 25 Distribution files 7 Do_chat 27, 43 DOOR.SYS 7, 9, 12, 14, 26, 73 Universal format 7 Variables 23 Doors 16 Doors opened 24 Doors_opened 24 DOS shell 17, 20 DOS Window 20, 54, 79, 81, 84, 86, 88, 89 Downbytes 24 Download bytes 24 Downloads 24 DSZ 20 DTR 20, 27, 44 Dv_here 19, 27, 45 Dv_pause 18, 27, 32, 46, 47 Editor 8 control characters 8 Elap_time 27, 47 Empty 27, 48, 56 Endview 25 Event_time 24 Expert 23 Files checking for existence of 27, 29 configuration 9, 15 Page 106 GAP Communications GAPCDR displaying 25, 91 DOOR.SYS 7, 9, 14 GAPCDR.H 8, 11 GAPSTRUC.H 8 PCBOARD.SYS 14 First name 24 Fix_color 27, 49 Flag 25 Floating point 8, 13, 55 Fname 24 Full name 24 Function calling 13 Function keys 17 Functions access1 27, 29 ansi 30 backspace 31 ckeypress 32 clear_scrn 33 clr_buf 34 cls 33, 35 cls_all 36 comgetc 20, 37 comgetd 20, 38 computb 39 computc 20, 40 computs 20, 41 cursoff 42 curson 42 do_chat 43 DOS Window 20 dtr 44 dv_here 19, 45 dv_pause 18, 46 elap_time 47 empty 48, 56 fix_color 49 gapputc 50 gapputs 51 get_attr 20, 54 get_random 55 get_string 48, 56 getakey 52 getkeyc 53 init_ansi 58 init_com 59 init_door 10, 11, 60 init_port 19, 20, 61 Page 107 GAP Communications GAPCDR iscd 62 leave 11, 12, 63 lputc 64 lputs 64 more 65 nl 66 no_carrier 18, 67 pagesysop 68 pause 69 putkey 70 read_cnf 9, 10, 11, 71 read_doorsys 73 read_gapuser 12, 74 read_pcbsys 12, 75 read_pcbuser 76 read_score 77 reset_port 19, 78 rest_cbreak 80 rest_int10 81 restore_screen 79 rts 82 rxempty 83 save_screen 84 set_attr 86 set_cbreak 87 set_cord 88 set_int10 89 set_port 19 set_status 90 setport 85 show_file 91 show_mess 51, 92 time_credit 94 time_left 95 timer 18, 93 trim 96 update_clock 97 wrap_word 98 write_gapuser 99 write_pcbsys 101 write_pcbuser 102 write_score 103 GAPCDR.H 11 Gapputc 27, 50 Gapputs 27, 51 GAPSTRUC.H 8, 53 Gendir 26 Get_attr 20, 27, 54 Page 108 GAP Communications GAPCDR Get_random 27, 55 Get_string 27, 48, 56 Getakey 27, 52 Getkeyc 27, 53 Gotdv 18 Goto 13 Handle 24 Header files GAPCDR.H 8, 11 GAPSTRUC.H 8, 53 Home phone number 24 Hphone 24 Init_ansi 27, 58 Init_com 27, 59 Init_door 10, 11, 27, 60 Init_port 19, 20, 27, 61 Initializing ANSI driver 11, 49, 58 interrupt handlers 11, 85 program 11, 54, 58, 59, 60, 71, 73, 85, 87 strings 27, 48, 56 Input from com port 20, 27, 37, 38, 83 from local & remote 27, 32, 46, 52, 56 from local keyboard 27, 53 Instatus 25 Interrupt handlers BIOS 81, 89 communications 19, 63, 78 CTRL-Break 11, 63, 80, 87 IRQ 9, 15, 25, 71, 85 Iscd 27, 62 Keyboard 32, 46, 52, 53, 56 timeout 32, 56 Last date user was on 24 Last name 24 Last new files scan 24 Last_new 24 Lastdate 24 Leave 11, 12, 27, 63 Level 23 Line feed 26 Lines 25, 65, 66 Linking 12 Lname 24 Local 18, 23 Functions cls 27, 35 Page 109 GAP Communications GAPCDR cls_all 27, 36 cursoff 27, 42 curson 27, 42 getkeyc 27, 53 lputc 27, 64 lputs 27, 64 Local mode 12, 18 Lowercase characters 25, 56 Lputc 27, 64 Lputs 27, 64 Maindir 26 Make_sound 27 Maxbytes 24 Maxfiles 23 Maximum bytes available 24 Maximum files available 23 Mesleft 24 Messages left 24 Minsleft 23 Minutes left at door start 23 More prompt 25, 27, 65 Multi 12, 23 Multi user 12, 17, 29 Name of the BBS 26 NL 27, 66, 92 No clock 25 No_carrier 18, 19, 27, 67 Node 23 Node number 23 Non Stop mode 25 Normal 25 Noup 25, 56 Novice 23 NS 25, 65 Number of downloads 24 Number of times on 24 Output to com port 20, 27, 39, 40, 41 to local & remote 27, 28, 50, 51, 92 to local screen 27, 64 Page 23 Page bell 17, 23, 68 Page length 23, 65 Pagesysop 27, 68 Parity 23 Pascal function calling 13 Password 24 Page 110 GAP Communications GAPCDR Path to DOOR.SYS 26 Pause 27, 69 Pausing 93 PCBOARD.SYS 14 PKUNZIP 20 Port 18, 19, 23, 71, 85 Printer 23 Printf 12 Prompts more 65 pause 69 Putkey 27, 70 Random number generator 11, 27, 55 Read_cnf 9, 10, 11, 27, 71 Read_doorsys 28, 73 Read_gapuser 12, 28, 74 Read_pcbsys 12, 28, 75 Read_pcbuser 28, 76 Read_score 28, 77 Realcredit 23 Receive buffer 32, 34, 37, 38, 83, 85 Recnum 24 Redisplay 25 Remote user 23 Remote user's bps rate 23 Reset_port 19, 28, 78 Rest_cbreak 28, 80 Rest_int10 28, 81 Restore_screen 28, 79 Rts 28, 82 Rxempty 28, 83 Save_screen 28, 84 Scan codes 53 Scoreboard 77, 103 Screen 23, 79, 84 clearing 33, 35, 36 color 54, 64, 86 cursor 42 full 65 Set_attr 28, 86 Set_cbreak 28, 87 Set_cord 28, 88 Set_int10 28, 89 Set_status 28, 90 Setport 19, 28, 85 Shell to DOS 17 Show_file 28, 91 Show_mess 28, 51, 92 Page 111 GAP Communications GAPCDR Single user 12, 23 Starttime 25 Status line displaying 17, 25, 90 protected 17 Strings initializing 27, 48, 56 receiving from local & remote 27, 48, 56 removing spaces from 96 sending to com port 27, 41 sending to local & remote 27, 51, 92 sending to local screen 27, 64 Strtime 26 Structures 26 Subscrip 24 Sysname 26 Sysop batch file 16 function keys 17 functions 14, 17 setup 14 Sysop's name 26 System files 14, 74, 75, 76, 99, 101, 102 Temptime 25 Time 25 Time credits 23, 94 Time door opened 25 Time slice 18, 32, 38, 45, 46, 47 Time user has left 25, 47, 52, 95 Time_credit 28, 94 Time_left 28, 95 Timecredit 14, 25 Timeleft 25, 32, 52, 95 Timenow 25 Timeout 32 Timer 18, 28, 93 Timeson 24 Total uploads 24 Trim 28, 96 Twit 17 Upbytes 24 Update_clock 28, 97 Updating status line 25 Upload bytes 24 Uploads 24 Uppercase characters 25, 56 Usemore1 25 User Record 26 Page 112 GAP Communications GAPCDR User's birth date 26 User's business phone 24 User's first name 24 User's full name 24 User's Handle 24 User's home phone 24 User's home town 24 User's last name 24 User's password 24 User's record number 24 User's security level 23 Userbaud 23 Username 24 Variables ANSI 8, 22 Defines NO 22 YES 22 DOOR.SYS alarm 23 baud 18, 23 bell 23 bphone 24 city 24 color 23 curbytes 24 curfiles 23 dflt_color 23 doors_open 24 downbytes 24 downloads 24 event_time 24 expert 23 fname 24 handle 24 hphone 24 last_new 24 lastdate 24 level 23 lname 24 local 18, 23 maxbytes 24 maxfiles 23 mesleft 24 minsleft 23 multi 12, 23 node 23 page 23 Page 113 GAP Communications GAPCDR parity 23 password 24 port 18, 19, 23 printer 23 realcredit 23 recnum 24 screen 23 subscrip 24 timeson 24 upbytes 24 uploads 24 userbaud 23 username 24 Global anystring 26 base_add 25 bbs_dir 26 birthday 26 board_name 26 BS 26 chat 25 clockon 25 column 25 CRLF 26, 51 curtime 26 endview 25 flag 25 gendir 26 gotdv 18 instatus 25 IRQ 25 lines 25 maindir 26 normal 25 noup 25, 56 NS 25 redisplay 25 starttime 25 strtime 26 sysname 26 temptime 25 timecredit 14, 25 timeleft 25 timenow 25 usemore1 25 view 25 wordwrap 25 Structures Page 114 GAP Communications GAPCDR pcbsys 26 pcbuser 26 user 26 View 25 Window 20, 79, 81, 84, 86, 88, 89 Wordwrap 25, 70, 98 Wrap_word 28, 98 Write_gapuser 28, 99 Write_pcbsys 28, 101 Write_pcbuser 28, 102 Write_score 28, 103 Page 115